Skip to content

notebooks: Reorganization in preparation for editing #475

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
validbeck merged 14 commits into from
Feb 11, 2026
Merged

notebooks: Reorganization in preparation for editing #475

validbeck merged 14 commits into from
Feb 11, 2026

Conversation

@validbeck
Copy link
Collaborator

@validbeck validbeck commented Feb 9, 2026 •
edited
Loading

Pull Request Description

What and why?

sc-14582

In preparation for editing the rest of our Jupyter Notebooks, I shuffled some of our notebooks around and better defined the categories in which the notebooks live in hopes of making the user journey for finding topics and samples more intuitive.

OLD NEW
Screenshot 2026-02-09 at 2 48 25 PM Screenshot 2026-02-09 at 2 48 55 PM

Major changes

1. Renamed code_samples/ to use_cases/

  • All content under notebooks/code_samples/ was moved to notebooks/use_cases/.
  • This affects the domain-specific demo notebooks: agents/, capital_markets/, code_explainer/, credit_risk/, model_validation/, nlp_and_llm/, ongoing_monitoring/, regression/, and time_series/.
  • The only exceptions were the custom_tests/ notebooks, which were moved to how_to/ instead (refer to below).

2. Reorganized how_to/ into topic-based subdirectories

The flat notebooks/how_to/ folder was reorganized into a nested structure with clear subcategories:

New subdirectory Content moved in
how_to/data_and_datasets/ Dataset feature config, loading predictions, raw data, dataset/model objects
how_to/metrics/ Unit metrics, logging metrics over time
how_to/scoring/ Score assignment tutorial
how_to/tests/explore_tests/ Exploring tests and test suites
how_to/tests/run_tests/ Running dataset-based and comparison tests
how_to/tests/run_tests/configure_tests/ Filtering columns, multiple datasets, customizing descriptions, using RawData, IDing PII in tests
how_to/tests/run_tests/documentation_tests/ Running documentation sections/tests with config, multiple results
how_to/tests/custom_tests/ Implementing custom tests, external test providers (moved from code_samples/custom_tests/)

3. Moved images attached to notebooks into the same directories that the notebooks live in

  • Instead of images living loose in notebooks/images I just shuffled them into the same (sub)directories that the notebooks live in as that is easier to associate and find.
  • Misc. images that didn't seem to be used anywhere I just plunked in code_sharing/images for now.

4. Updated all internal references

  • Fixed cross-notebook links (e.g., code_samples/ references updated to use_cases/, how-to links updated to new paths) across quickstart, tutorial, template, and code-sharing notebooks.
  • Updated scripts/run_e2e_notebooks.py so the e2e test runner points to the correct new paths.
  • Updated notebooks/README.md with revised folder descriptions.
  • Updated the image paths for notebooks that have images.

Why

The previous structure had some naming/organizational issues:

  • code_samples/ was a vague name — renaming it to use_cases/ better describes that these are end-to-end examples for specific domains (credit risk, NLP/LLM, time series, etc.).
  • how_to/ was a flat folder with many unrelated notebooks at the same level — grouping them into topic-based subdirectories (data_and_datasets, metrics, tests, security, etc.) makes it much easier to navigate and find relevant guides.
  • Custom test notebooks were under code_samples/ but are really "how to" content about using a ValidMind feature, so they were moved to how_to/tests/custom_tests/ where they logically belong.

How to test

n/a

What needs special review?

Important

Please make sure that the new categories assigned to notebooks make sense and are logical as I don't have as deep of an understanding of our notebook content as I'd like.

Dependencies, breaking changes, and deployment notes

Note

Links to the moved notebooks have also all been updated notebook side — they will be updated documentation side once this PR is approved and I am able to pull the new notebooks in under this PR: validmind/documentation#1168

Release notes

Release notes will go out with the documentation side PR as there will be additional navigation changes for how the notebooks are linked/structured in the docs.

Checklist

  • What and why
  • Screenshots or videos (Frontend)
  • How to test
  • What needs special review
  • Dependencies, breaking changes, and deployment notes
  • Labels applied
  • PR linked to Shortcut
  • Unit tests added (Backend)
  • Tested locally
  • Documentation updated (if required)
  • Environment variable additions/changes documented (if required)

@validbeck validbeck self-assigned this Feb 9, 2026
@validbeck validbeck added the internal Not to be externalized in the release notes label Feb 9, 2026
@github-actions
Copy link
Contributor

github-actions bot commented Feb 10, 2026

PR Summary

This PR systematically updates file paths, URLs, and image references across a wide array of project notebooks, templates, and scripts. The primary goal is to align all documentation with the new directory structure (e.g., moving some notebooks from the /code_samples/ folder to /use_cases/ and updating references under the /how_to/tests/ hierarchy). Key changes include:

  • Adjusting notebook paths to reference the correct folder (for example, updating links from code_samples to use_cases where appropriate).
  • Updating external links in markdown cells, such as those in the Explore tests, custom tests, and test configuration examples to point to the new URLs.
  • Modifying image paths so that screenshots and diagram references correctly load from updated relative directories.
  • Ensuring that inline code blocks and instruction texts maintain consistency in the way inputs, models, and datasets are documented.

These modifications improve navigation for users and maintain consistency within the documentation. The changes are non-functional in nature and aim to streamline the user experience by ensuring that links and file references point to the current, accurate locations in the repository.

Test Suggestions

  • Run the automated end-to-end notebook test script (e.g., 'scripts/run_e2e_notebooks.py') to verify that no notebooks fail due to missing files or broken links.
  • Manually review a subset of modified notebooks to ensure that image references render correctly and external links navigate to the updated URLs.
  • Utilize a link-checking tool or add a linting step to catch any broken internal or external URL references.

@validbeck validbeck mentioned this pull request Feb 10, 2026
Merged
15 tasks
cachafla
cachafla approved these changes Feb 11, 2026
View reviewed changes
Copy link
Contributor

@cachafla cachafla left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new layout is much better. I like use_cases/ a lot 🙌

@validbeck validbeck merged commit bfa2a9e into main Feb 11, 2026
8 checks passed
@validbeck validbeck deleted the beck/sc-14582/reorganize-jupyter-notebooks branch February 11, 2026 00:28
@validbeck validbeck mentioned this pull request Feb 12, 2026
Open
11 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cachafla cachafla cachafla approved these changes

@nrichers nrichers Awaiting requested review from nrichers

Assignees

@validbeck validbeck

Labels

internal Not to be externalized in the release notes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@validbeck @cachafla